{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Demo for Learning Rate Decay Application"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This demo will address how to make use of the learning rate scheduler in the context of a segmentation task. The scheduler allows for the learning rate to evolve predictably with training iterations (this will typically be a decay over time). This demo assumes you have a working installation of NiftyNet."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Preparation:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "1) Ensure you are in the NiftyNet root, and set this root as an environment variable:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os,sys\n",
    "import matplotlib.pyplot as plt\n",
    "import numpy as np\n",
    "niftynet_path='your/niftynet/path'  # Set your NiftyNet root path here\n",
    "os.environ['niftynet_config_home'] = niftynet_path\n",
    "os.chdir(niftynet_path)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "2) Acquire the data. We will make use of a publicly available hippocampus segmentation dataset in this demo. Prior to this you will need to create a file named 'config.ini' in your NiftyNet root folder with the following format:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```ini\n",
    "[global]\n",
    "home = /your/niftynet/path\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following code snippet will create the file for you:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "f = open(\"config.ini\", \"w+\")\n",
    "f.write(\"[global]\\n\")\n",
    "f.write(\"home = {}\".format(niftynet_path))\n",
    "f.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now you are ready to download the data which you can do by running the following cell:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "%run net_download.py decathlon_hippocampus -r"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The training data, labels, and test data will be downloaded into the */data/decathlon_hippocampus/* folder in your NiftyNet root directory."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The configuration file:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The configuration file in NiftyNet specifies all the parameters pertinent to the training/ inference task at hand including but not limited to: Training data location, network of choice, learning rate, etc. <br>\n",
    "\n",
    "In this instance a configuration file has been provided (learning_rate_demo_train_config.ini) with default settings for a segmentation training task. Note that these settings can be overriden in the command line or by simply editing the configuration file. For further information regarding the configuration file and the individual variables refer to the relevant documentation [here](https://niftynet.readthedocs.io/en/latest/config_spec.html)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Training a network from the command line:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To run this application from the command line using the variables specified in the configuration file:\n",
    "\n",
    "```python net_run.py train -a niftynet.contrib.learning_rate_schedule.decay_lr_application.DecayLearningRateApplication \n",
    "                        -c /demos/Learning_Rate_Decay/learning_rate_demo_train_config.ini --max_iter 90```\n",
    "\n",
    "With the current setup, the learning rate will halve every three iterations. NiftyNet will create *logs* and *models* folders to store training logs and models, respectively. <br>\n",
    "\n",
    "The following cells exemplify the potential benefit of having a decaying learning rate: Two networks are trained, one lacks any learning rate scheduling, the other has a learning rate schedule that decays the learning rate by 2% every 5 iterations. By looking at the loss curves we can see that the latter converges towards a lower cross entropy despite the exact same initialisation:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "import sys\n",
    "import niftynet\n",
    "sys.argv=['','train','-a','demos.Learning_Rate_Decay.Demo_applications.decay_lr_comparison_application.DecayLearningRateApplication','-c',os.path.join('demos','Learning_Rate_Decay','learning_rate_demo_train_config.ini'),'--max_iter','500','--lr','25.0','--model_dir','./models/decay']\n",
    "niftynet.main()\n",
    "sys.argv=['','train','-a','demos.Learning_Rate_Decay.Demo_applications.no_decay_lr_comparison_application.DecayLearningRateApplication','-c',os.path.join('demos','Learning_Rate_Decay','learning_rate_demo_train_config.ini'),'--max_iter','500','--lr','25.0','--model_dir','./models/no_decay']\n",
    "niftynet.main()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 800x360 with 1 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "decay_model_dir = niftynet_path + '/models/decay'\n",
    "no_decay_model_dir = niftynet_path + '/models/no_decay'\n",
    "\n",
    "with open(os.path.join(decay_model_dir, 'training_niftynet_log'), 'r') as f:\n",
    "    lines = f.readlines()\n",
    "    data = ' '.join(lines)\n",
    "    last_run = data.rpartition('Parameters from random initialisations')[-1]\n",
    "    last_run_lines = last_run.split('\\n')\n",
    "    raw_lines = [l.split(',')[1:] for l in last_run_lines if 'loss' in l]\n",
    "    iterations = [int(l[0].split(':')[1].split(' ')[-1]) for l in raw_lines]\n",
    "    decay_CE_losses = [float(l[1].split('=')[1]) for l in raw_lines]\n",
    "\n",
    "with open(os.path.join(no_decay_model_dir, 'training_niftynet_log'), 'r') as f:\n",
    "    lines = f.readlines()\n",
    "    data = ' '.join(lines)\n",
    "    last_run = data.rpartition('Parameters from random initialisations')[-1]\n",
    "    last_run_lines = last_run.split('\\n')\n",
    "    raw_lines = [l.split(',')[1:] for l in last_run_lines if 'loss' in l]\n",
    "    iterations = [int(l[0].split(':')[1].split(' ')[-1]) for l in raw_lines]\n",
    "    no_decay_CE_losses = [float(l[1].split('=')[1]) for l in raw_lines]\n",
    "\n",
    "fig = plt.figure(figsize=(10, 4.5), dpi=80)\n",
    "plt.plot([np.mean(no_decay_CE_losses[l:l+10]) for l in range(0,len(no_decay_CE_losses), 10)],\n",
    "         color='red', label='Constant lr')\n",
    "plt.plot([np.mean(decay_CE_losses[l:l+10]) for l in range(0,len(decay_CE_losses), 10)],\n",
    "         color='green', label='Decaying lr')\n",
    "plt.title(\"Smoothed loss curves\", fontsize=20)\n",
    "plt.legend(fontsize=16)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Customising the learning rate scheduler:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Currently the application is set up such that the learning rate is halved every third training iteration. This is an arbitrary default setup and it is likely you'll want to alter this to suit your purposes. Let's look at the *set_iteration_update* method of the *DecayLearningRateApplication* class in the application (*decay_lr_application.py*):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def set_iteration_update(self, iteration_message):\n",
    "    \"\"\"\n",
    "    This function will be called by the application engine at each\n",
    "    iteration.\n",
    "    \"\"\"\n",
    "    current_iter = iteration_message.current_iter\n",
    "    if iteration_message.is_training:\n",
    "        if current_iter > 0 and current_iter % 3 == 0:\n",
    "            self.current_lr = self.current_lr / 2.0\n",
    "        iteration_message.data_feed_dict[self.is_validation] = False\n",
    "    elif iteration_message.is_validation:\n",
    "        iteration_message.data_feed_dict[self.is_validation] = True\n",
    "    iteration_message.data_feed_dict[self.learning_rate] = self.current_lr"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The relevant subsection we will want to focus on is contained in two lines:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "if current_iter > 0 and current_iter % 3 == 0:\n",
    "    self.current_lr = self.current_lr / 2.0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The second line contains the logic that changes the learning rate wheras the first line stipulates the condition under which this will occur. As such only these two lines need to be changed if the scheduling is to be changed. For example, if we'd like to reduce the learning rate by 1% every 5 iterations then this snippet of code would look like:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "if current_iter > 0 and current_iter % 5 == 0:\n",
    "    self.current_lr = self.current_lr * 0.99"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Similarly, if we'd like for the learning rate to decay exponentially every iteration modulated by some factor *k*:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "if current_iter > 0:\n",
    "    self.current_lr = self.current_lr * np.exp(-k * current_iter)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Summary:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this demo we have covered the following: <br>\n",
    "1. How to run NiftyNet using the learning rate decay application from the command line and from python code directly\n",
    "2. How to edit the learning rate application to schedule the learning rate to suit one's needs"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
